package stardust.product.platform.webc.annotation;


import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.text.SimpleDateFormat;
import stardust.product.platform.webc.WebcParameterConvert;


/**
 * 请求参数标注，目前仅支持基本数据类型、包装类型和一维数组的自动转换。 <br/>
 * 用于标明请求参数的来源以及转换方式信息。 <br/>
 * <p/>
 * @see Handler
 * @see Renderer
 * @author ChenChang
 */
@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Parameter
{

  /**
   * 参数来源，当在Servlet环境中时这是通过浏览器表单传递的参数名称。<br/>
   * <p/>
   * @return 参数来源信息或参数名称。
   */
  String value();
  
  /**
   * 参数必要标志。<br/>
   * <p/>
   * @return  是否必须提供参数，如果为<tt>true</tt>值表示是必须的。
   */
  boolean required() default false;

  /**
   * 格式化参数，一般用于对日期时间类型的转换。<br/>
   * <p/>
   * @return  格式化字符串，如果是日期时间类型请参考{@link SimpleDateFormat}里提供的格式化参数。
   */
  String format() default "";
  
  /**
   * 自定义参数转换，实现{@link WebcParameterConvert}接口以支持对复杂数据模型的转换。<br/>
   * 例如通过自定义代码将多个参数传递到一个对象的多个属性当中，以及将JSON格式的字符串转换为Java对象。<br/>
   * <p/>
   * @return 默认为空转换器，如果不是默认转换器将调用指定类的方法实现自定义转换。
   */
  Class<? extends WebcParameterConvert> converter() default WebcParameterConvert.class;
  
}
